
For an updated version, see:
http://mgarcia.org/Blog/2021-10-23-Linux-Development-Virutal-Machine-for-32blit-SDK?action=edit



ETA prime, did a review of the PicoSystem and threw down a challenge to play some community made games on his next video!
https://www.youtube.com/watch?v=m_5voWb7MYU

PicoSystem and VGA Board a [very similar](https://github.com/32blit/32blit-sdk/blob/master/docs/pico.md#board-specific-details), so if you choose to get a VGA Board instead, I think that should be fine.


I'm not an expert, there's a lot of noob hacks here, but to encourage others, here are my notes on setting up.

32blit is very impressive how it can target so many platforms!
Sorry I wont be mentioning Mac or chrome OS's, I'm not familiar at all with them.

I'm mostly in the 32blit discord (Chat) - https://discord.gg/7qM9ftC
But I can try and answer/help here to.




**General noob tips:**

The 32blit documentation is pretty good, but I still got caught out here and there.
Keep folders names simple, ie no spaces or none ASCI chars, including user name!

Make sure your .profile or .bash_profile etc can be run correctly in your window terminal before starting!
Sometimes they have access issues, ie a quick fix can be:
chmod 777  $HOME/.bash_profile


If you want to build faster use:
make -j2 
The number is the threads to run, the more the faster

I'm a git,cmake,arm noob, it's best to git clone each repo then to download them as zips, this is required by some, but best to do for all, IE:
git clone -b master https://github.com/raspberrypi/pico-sdk.git


Each target has it's own build folder in the 32blit-sdk (or your game) folder
ie build.stm32 build.em etc.

Here is the directory structure at the end.
> 
> $HOME/	
>> 	emsdk
>> 	pico-sdk
>> 	32blit-tools
>> 	pico-extras
>> 	pico-sdk
>> 	gcc-arm-none-eabi-9-2020-q2-update (not required, and probably a me thing) 	
>>	.local/bin (auto generated - location of the 32blit tool)
>>	32blit-beta (latest branch for pico devices)
>  
>>	32blit-sdk/
> > 	build
> >		build.picosystem
> >		build.vgaboard
> >		build.win64
> >		build.em 
> >		build.stm32





**My setup.**

I thought I would use a new linux flavor, I went with MX (debian based) and picked XFCE (and unknowingly stable).
Here are the links:
https://distrowatch.com/?newsid=11206
–Xfce (our flagship desktop) MX-21_x64, with a standard 64 bit kernel and hardware support from Debian Stable. Suitable if your PC is a few years old.
https://mxlinux.org/download-links/#Mirrors 
https://sourceforge.net/projects/mx-linux/files/Final/Xfce/MX-21_x64.iso/download?use_mirror=ixpeering&use_mirror=ixpeering&r=https%3A%2F%2Fmxlinux.org%2F

This is helpful for XFCE:
https://askubuntu.com/questions/876567/ask-before-running-script-in-thunar


Eclipse, my IDE of choose for over 20years now!
https://www.eclipse.org/downloads/packages/release/2021-09/r/eclipse-ide-cc-developers

I installed this to a Virtual Box image, so it's self contained, the USB devices are automatically forward to the VM.


**-----------------------------------------------------------------**
***linux***

After install, run:
sudo apt update



add gdb to the list of things to install, if you plan on debugging natively!
Follow: https://github.com/32blit/32blit-sdk/blob/master/docs/Linux.md


sudo apt install git gcc g++ gdb gcc-arm-none-eabi cmake make \
python3 python3-pip python3-setuptools \
libsdl2-dev libsdl2-image-dev libsdl2-net-dev unzip



The OS app control keys are (see hardware-test app):

Dpad = arrow keys or WASD
A = Z key
B = X key
X = C key
Y = V key

Home = 1 key
Menu = 2 or ESC key

Joystick = Mouse within app screen
Joystick press = 3 key

Tilt controls, I don't know.


**-----------------------------------------------------------------**
***32blit tool***

I found this part a bit confusing.

In your $HOME folder (not 32blit root)
git clone the https://github.com/32blit/32blit-tools

It also requires:
https://github.com/pimoroni/boilerplate-python

I don't know the git commands to do it, but basically I just download the zip and extract it into the 32blit-tools dir.

git clone https://github.com/32blit/32blit-tools.git 
cd 32blit-tools
git clone https://github.com/pimoroni/boilerplate-python.git 
cp -a boilerplate-python/* .



Next, I had issues running pip3, not in the path (of sudo possibly), again, I brought forced scripts that used pip3, replacing it with 
python3 -m pip

pip3 install 32blit
or
python3 -m pip  install 32blit

That will build tool and install the tool into ~/.local/bin and add the path to your env file setting, ie .profile 



Setup and build the linux native
From: https://github.com/32blit/32blit-sdk/blob/master/docs/Linux.md

Setup it, in user root (ie ~):

git clone https://github.com/32blit/32blit-sdk.git

Building it is uneccesary, except to test the toolchain and see the demo's etc.

cd ~/32blit-sdk
mkdir build
cd build
cmake .. 
make -j2

run and test the exe's 




**-----------------------------------------------------------------**
***stm32 (32blit)***

AKA 32blit: https://32blit.com/
Follow: https://github.com/32blit/32blit-sdk/blob/master/docs/32Blit-Firmware.md#building--flashing-the-32blit-firmware



cd ~/32blit-sdk
mkdir build.stm32
cd build.stm32
cmake .. -DCMAKE_TOOLCHAIN_FILE=$HOME/32blit-sdk/32blit.toolchain

make -j2


When linking the executables, you'll see a warning like this:

[ 97%] Building CXX object CMakeFiles/game.dir/assets.cpp.obj
[100%] Linking CXX executable game.elf
/home/dev/gcc-arm-none-eabi-9-2020-q2-update/bin/../lib/gcc/arm-none-eabi/9.3.1/../../../../arm-none-eabi/bin/ld: warning: cannot find entry symbol Reset_Handler; defaulting to 00000000900001a0
Building game.bin
   text	   data	    bss	    dec	    hex	filename
  21688	    904	   2280	  24872	   6128	/home/dev/eclipse-workspace/test/build.stm32/game.elf
There are 42 section headers, starting at offset 0x988a0:



The reason for this is because games don't have a reset handler (only the firmware does).


On my debian stable, or the MX repo the gcc-arm-none-eabi package (from 2018) couldn't build the stm32.
I had to "brute force it"... and downloaded the tar.bz2 file and extracted it and manually fixed up the paths in .profile
PATH="$HOME/gcc-arm-none-eabi-9-2020-q2-update/bin:$PATH"

gcc-arm-none-eabi-9-2020-q2-update-x86_64-linux.tar.bz2 from https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads
I had to specifcy -DPICO_TOOLCHAIN_PATH=$HOME/gcc-arm-none-eabi-9-2020-q2-update in stm32/pico cmake commands below.




Before plugging in 32blit or pico device,  do this, give your user access to serial device!
Note: Pico uses /dev/ttyACM0
https://github.com/esp8266/source-code-examples/issues/26

sudo usermod -a -G tty username


32blit can printf to the TTY terminal, install one, ie: 
sudo apt-get install putty cu minicom screen
I found screen to work the easiest (no params), ie:
screen  /dev/ttyACM0

Updated the firmware, if you haven't every or it's old.

Put the 32blit in DFU mode (hold X/Y and press reset) , winplug the USB cable in.
32blit flash firmware/firmware.bin
or
make firmware-update.flash

next install the launcher:
32blit install launcher/launcher.blit
or
make launcher.flash

intall all the other demos (see bottom of Makefile for more info):
make install DEMO-NAME.flash


You now should have a working and demo loaded 32blit!

**-----------------------------------------------------------------**
***Emscripten***


Follow:
https://github.com/32blit/32blit-sdk/blob/master/docs/Emscripten.md


git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install latest
./emsdk activate latest
source ./emsdk_env.sh


make sure paths are correctly executed when a new shell/terminal is open,it should automatically run source $HOME/emsdk/emsdk_env.sh


cd ~/32blit-sdk
mkdir build.em
cd build.em
emcmake cmake .. -D32BLIT_DIR=$HOME/32blit-sdk
make -j2 (or more, takes a long time!)

I like to create a script file that starts the server is helpful:
#!/bin/bash
python3 -m http.server

Run in a terminal and CTRL C to stop it.


I don't know why, but firefox doesn't like it, chrome browser works fine.
The keyboard buttons (from hardware-test app): 
http://0.0.0.0:8000/32blit-sdk/build.em/examples/hardware-test/hardware-test.html

Same as the native OS controls.



**-----------------------------------------------------------------**
***windows exe***



I use:
sudo apt-get install mingw-w64
Not the documented:
sudo apt install gcc-mingw-w64 g++-mingw-w64


after: sudo mkdir -p /opt/local/

make it accessible:
sudo chmod -R 777 /opt/local

cd  /opt/local 

and download and extract as per instructions

Follow: https://github.com/32blit/32blit-sdk/blob/master/docs/Windows-WSL.md#installing-the-mingw-compilertools

in 32blit-sdk root
mkdir build.win64
cd build.win64

cmake .. -DCMAKE_TOOLCHAIN_FILE=../mingw.toolchain
make -j2


optionally install wine
sudo apt install wine64
installs as: /usr/bin/wine64-stable
test: /usr/bin/wine64-stable examples/geometry/geometry.exe

**-----------------------------------------------------------------**
***setting up PicoSystem / VGA BOARD***


VGA BOARD
https://shop.pimoroni.com/products/pimoroni-pico-vga-demo-base

PicoSystem
https://shop.pimoroni.com/products/picosystem


Both being based on the RP Pico, require the same source code, nothing is built in these folders.


https://github.com/raspberrypi/pico-sdk

Also read the PDF section 2.1. Get the SDK and examples
https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf


In your $HOME folder (not 32blit root)
git clone -b master https://github.com/raspberrypi/pico-sdk.git
cd pico-sdk
git submodule update --init


cd ~

git clone -b master https://github.com/raspberrypi/pico-extras.git

cd into ~/32blit-sdk

Follow: https://github.com/32blit/32blit-sdk/blob/master/docs/pico.md



**-----------------------------------------------------------------**
***pico bleading edge!***


Both devices are under heavy development currently!

The newer branches of 32blit-sdk has better performance and feature support ie USB support for VGA board, it's called 32blit-beta instead of 32blit-sdk.
But the two can be used together by using the beta folder with pico devices, ie:


cd $HOME

git clone -b pico-all-the-boards --single-branch https://github.com/Daft-Freak/32blit-beta.git
This branch requires the latest tinyUSB

cd $HOME/pico-sdk/lib/
mv tinyusb tinyusb.orig
git clone https://github.com/hathach/tinyusb

The new source code is referenced from the 32blit-sdk root builds, ie:

In 32blit-sdk root
mkdir build.picosystem
cd build.picosystem
cmake .. -D32BLIT_DIR=$HOME/32blit-beta  -DPICO_SDK_PATH=$HOME/pico-sdk -DPICO_EXTRAS_PATH=$HOME/pico-extras  -DPICO_BOARD=pimoroni_picosystem

make -j2



The VGA board is similar as above, but with -DPICO_BOARD=vgaboard instead of -DPICO_BOARD=pimoroni_picosystem

repeat for vgaboard into new build folder, ie:

in 32blit-sdk root
mkdir build.vgaboard
cd build.vgaboard



mkdir build.vgaboard
cd build.vgaboard

cmake .. -D32BLIT_DIR=$HOME/32blit-beta  -DPICO_SDK_PATH=$HOME/pico-sdk -DPICO_EXTRAS_PATH=$HOME/pico-extras  -DPICO_BOARD=vgaboard

make -j2





**-----------------------------------------------------------------**
** new project**

read https://github.com/32blit/32blit-boilerplate/

cd into the folder you want to start a in project, ie:
cd $HOME/eclipse-workspace


git clone https://github.com/32blit/32blit-boilerplate.git PROJECT_NAME

cd PROJECT_NAME


next you have to build it to set the executable.

mkdir build
cd build
cmake .. -D32BLIT_DIR=$HOME/32blit-sdk -DCMAKE_BUILD_TYPE=Debug
make -j2
run it: ./game

You can create a new build folder for a release target, etc

I'm sure there's better ways to work with eclipse and cmake projects, but here's how I do it:
import the PROJECT_NAME folder as an existing code as makefile project --- C++ project, "
right click build->game -> run as -> local C++ app - double clic C/C++ app
click menu run -> run configuration, click 'build configuration' append build/ to  build director: ie ${workspace_loc/PROJECT_NAME:}/build/ click apply

Now if you change game.cpp it'll compile first before running.
Next, set the default header full paths for include SDL2/32blit-sdl/32blit.

right click main project -> properties -> C/C++ general -> Paths and sysmbols,  add to include directories individualy, tick add to all config and languages:
/opt/local/x86_64-w64-mingw32/include/SDL2
/home/USERNAME/32blit-sdk/32blit-sdl
/home/USERNAME/32blit-sdk/32blit

Note: change USERNAME to your user name

click apply.


right click main project, index -> rebuild 

CTRL left click a 32blit classes/function and you should drill down into it, ect.

To debug, set a break point and click debug icon



To target other platforms, create a new build folder and use the same cmake parameters as above when building the 32blit-sdk examples.
IE:
cd PROJECT_NAME
mkdir build.em
cd build.em
emcmake cmake .. -D32BLIT_DIR=$HOME/32blit-sdk
make

run
python3 -m http.server
launch chrome browser, click game.html, close browser
ctrl -c 










